TConversion Version 1.01

Copyright (c) by P.A.S.S and Ron van Petegem (ronvanpetegem@compuserve.com)

All components and Classes described in this file are captured under the aforementioned Copyright

Note that all components have been tested for resource/Memory leaks using TurboPowers MemorySleuth and no Memory or resource leaks were detected.

CONTENTS

1 - Overview
2 - Installation
3 - Component methods, events and functions
4 - License information
5 - DISCLAIMER

1 - Overview
===========
This package includes 6 components and 1 Class:
TConvEdit, TAlignEdit, TNumEdit, TDBMoreEdit and TConvFloatField. There is also a TCustomalignEdit component you can use as a base class for edit controls that require a alignment and FakeTabKey property .

TConversion is the underlying class that is used with the TConvEdit and TConvFloatField components.

All Edit components support a FakeTabKey property to allow the enter, Up Arrow/Down Arrow key to work as tab keys. Unlike some other edit controls with similar features, these work with any 32 bit version of windows. They also support a Alignment property and a FocusedAlign property, this allows for you to alter alignment depending on focus.

TConvEdit is a component that allows a end user to pick the input unit of his choice while the programmer can call on the output unit for calculations. This allows more flexibility both for the end user as well as the programmer. The programmer can always refer to the same output no matter what input unit is selected.

TAlignEdit is a edit control with FakeTabKey and Alignment/FocusedAlign support

TNumEdit is as TAlignEdit, but only allows numbers. There is also some additional formatting available.

TDBMoreEdit is a standard TDBEdit but with FakeTabKey support. Alignment is usported through the standard DelphiTFfield components.

TConvFloatField is a TFloatfield with Conversion support. For example, this will allow a database to have a Length field in Centimeter, but have the user input in a unit of his own choice i.e. Inches. The data is always saved to the database in the format required by the programmer. This component is very powerful, as it can greatly reduce programming work. This component is specifically designed to allow a program to be adapted to work with Euro currency  without major changes to the existing programs.

It also allows programs to be localized without writing any or very little code i.e: Have a metric system for Europe and Imperial for the US.


2 - Installation:
============
To install, copy all files in a directory that is on the Delphi library path and "ConvFactors.Ini" to the windows directory. You can change the path to this file, but during designing, the file MUST be in the windows directory. (When you distribute and did not alter the location of this file then you must also copy this file to the windows directory)

Select "Install Component" from the Component menu. Select if you want to install in a new or existing package and select "ConvEditReg.Pas" in the Unit field name field. Set other fields as needed and click OK. Note that "TConvFloatField" is also registered to show up in the Delphi Fields editor. NOTE: There appears to be a bug with the Delphi routine that registers fields, If you would call the function with a existing field (Call register twice), you will get a error message when you select the New Field option from the menu. There is no harm done however, so not a real problem just annoying.

The Components are installed under the "Standard" and "Data Controls" tab, but you can alter these locations by editing the "ConvEditReg.Pas" file.

There is also a ConvertConst.pas file included that will allow for you to localize some string constants.

3 - Component methods, events and functions
=======================================
TCustomalignEdit:
------------------------
Inherits from: TCustomEdit.
New properties
    property Alignment: TAlignment = (taLeftJustify, taRightJustify, taCenter);
     - This is the text alignment when the control is not focused.

    property FocusedAlign: TAlignment = (taLeftJustify, taRightJustify, taCenter);
     - This is the text alignment when the control is focused. If you do not want this to change just set it the same as Alignment.

    property FakeTabKeys: TFakeTabKeys = (ftNone, ftEnter, ftUpDown, ftBoth);
    - ftNone: Standard behavior, Focus only moves with tab keys.
    - ftEnter: Focus moves with Tab and Enter keys
    - ftUpDown Focus moves with Tab and Up/Down arrow keys
- ftBoth Focus moves with Tab, Enter and Up/Down arrow keys.

Hidden Properties as compared to standard TEdit:
    property Text;
    property PassWordChar;
    property CharCase;

TAlignEdit
---------------
Inherits from TCustomAlignEdit.
No new properties

Publishes 
    property Text;
    property PassWordChar;
    property CharCase;

TNumEdit
--------------
Inherits from TCustomAlignEdit
For formatting it uses the Delphi FloatToStrF function or the FormatFloat function depending if the CustomFormat property is empty.

New properties:
    property NumType: TnumType = (ntFloat, ntInteger);
    Set this to change the type of number you want to work with

    property FloatValue: Extended
    Read/Write the float value. When NumType is ntInteger, this will return the number as a float

    property IntegerValue: Integer
    ReadWrite the integer value. When NumType is ntFloat this will return the integer portion of the number

    Property FloatType:TFloatFormat = (ffGeneral, ffExponent, ffFixed, ffNumber, ffCurrency);
    Property Precision: Integer;
    Property Digits: Integer;
    Set these to influence the formatting of the text. Please consult the Delphi help file for information

    Property CustomFormat: String;
    If this is set the program is using the FormatFloat function instead of FloatToStrF for formatting.

TConvEdit
--------------
Inherits from TNumEdit

New Properties

    Property Conversion: TConversion.
    See TConversion below

    Property UnitLabel: TLabel.
    Set this to associate TConvEdit with a Label. The label caption will now be set according to the Conversion.UnitIn property. This will ensure that the input unit is always correctly shown to the user.


TDBMoreEdit
-------------------
Inherits from TDBEdit.

New properties:

    property FakeTabKeys: TFakeTabKeys = (ftNone, ftEnter, ftUpDown, ftBoth);
    - ftNone: Standard behavior, Focus only moves with tab keys.
    - ftEnter: Focus moves with Tab and Enter keys
    - ftUpDown Focus moves with Tab and Up/Down arrow keys
- ftBoth Focus moves with Tab, Enter and Up/Down arrow keys.


TConvFloatField.
-----------------------
This is a VERY powerful component that allows your users to work with the unit of THERE choice while still recording the unit of YOUR choice in the database. I.E.: It allows for you to convert existing programs to work with EURO's with almost no change in code. Just replace some fields and allow your users to work with the currency of there choice.

New Properties

    Property Conversion: TConversion.
    See TConversion below

    Property UnitLabel: TLabel.
    Set this to associate TConvEdit with a Label. The label caption will now be set according to the Conversion.UnitIn property. This will ensure that the input unit is always correctly shown to the user.

To use this field
1 - double click a TTable or TQuery component to show the Fields editor. 
2 - Right click on the Fields editor and select New field..
3 - Under field properties, Type the name of the field name as it appears in the actual database table.
4 - Under field properties, Type ConvFloat or select ConvFloat  from the drop down box.
5 - Click ok.
6 - Select the new field in the Fields editor and set the conversion property as required.

REMEMBER, the UnitIn property is what the user edits, the UnitOut property is what actually gets written to the database. The AsFloat, AsText, etc.. properties continue to report the actual value as in the database. To get to the converted value use the functions/properties from TConversion.

TConversion.
------------------
TConversion is based on TPersistent, so it is NOT a component. Although it can work on its own, it is designed to work as a property with other components.

Note that you can add other conversion types and units to the ConvFactor.ini file provided they are linear conversions (1 step calculation). TConversion also allows for you to work with multiple Factor files, so you can decide what factor you like to distribute. 

TConversion also provide build in menu handling.

Type
  TUnitChangeEvent = procedure (Sender: TObject; UnitKind, UnitIn, UnitOut: String; Var Allow: Boolean) of object;

  TConversion = Class(TPersistent)
  Protected
    Procedure GetFactor;
    Procedure SetFactorFile(Value: String);
    Procedure MnuClick (Sender: TObject);
  Public
    constructor Create(aOwner: TComponent);
    Procedure DoConvert;
    Procedure SetTextValue(Value: String);
    Procedure Convert(Value: Extended);
    Procedure UnitsToMenu(P: TMenuItem; aType: String);
    Function GetUnitList(aList: TStrings; aKind: String):Boolean;
    Function GetTypeList(aList: TStrings):Boolean;
    Procedure SetMenuItem(Value: TMenuItem);
    Property Result: Extended Read FResult;
    Property InvResult: Extended Read FInvResult;
    Property Owner: TComponent Read FOwner;
  Published
    Property UnitKind: String index 0 Read FUnitKind Write SetConversion;
    Property UnitIn: String index 1 Read FUnitIn Write SetConversion;
    Property UnitOut: String index 2 Read FUnitOut Write SetConversion;
    Property Factor: Extended Read FFactor Write SetFactor;
    Property FactorFile: String read FFactorFile Write SetFactorFile;
    property MenuItem: TMenuItem Read FMenuItem Write SetMenuItem;
    property OnConvert: TNotifyEvent read FOnConvert write FOnConvert;
    property OnUnitChange: TUnitChangeEvent Read FOnUnitChange write FOnUnitChange;
  end;

Details:

    Property Result: Read only, Provides value of converted Input
    Property InvResult: read only. Inverts the result back to original input. Use this property when you need the actual input value of the user.
    Property Owner: TComponent: Read only. Provides access to the owner of TConversion.

    Property UnitKind: String Read/Write the kind of unit (Length, EURO, Temperature, Etc..)
    Property UnitIn: String Read/Write The input unit (Cm, Peseta, Celsius, etc..)
    Property UnitOut: String Read/Write The output unit (Cm, Peseta, Celsius, etc..)
    Property Factor: Read/Write Factor that is used for conversions.
    Property FactorFile: read/Write the file containing the conversion factors Default: ConvFactors.ini in the windows directory.
    property MenuItem: TMenuItem Read/Write the menu item that will contain a list of units that a user can select from.
    property OnConvert: TNotifyEvent: Happens immediately after conversion. Use it to update calculations or other components.
    property OnUnitChange: TUnitChangeEvent. Happens before the UnitKind, UnitIn or UnitOut is changes. This allows you to prohibit a change and/or to update any labels.

Procedures and Functions

Procedure DoConvert; Use this to force a conversion with the selected units. There is normally no need to call this directly as TConversion will call this when needed.

    Procedure SetTextValue(Value: String); Use this to invoke a conversion with a number of your choice. The value must be a string that represents a valid number.

    Procedure Convert(Value: Extended); Use this to invoke a conversion with a number of your choice. The value must be a valid number.

    Procedure UnitsToMenu(P: TMenuItem; aType: String); Use this to load a MenuItem of your choice with a UnitKind of your choice. The function will create a submenu under the MenuItem that you pass it. The menu onclick handler is provided by TConversion, all you need to do is pass the menuitem and you have a working menu.

    Function GetUnitList(aList: TStrings; aKind: String):Boolean; This function will load a TStrings/TStringList with the available units according to the aKind parameter. (See example program)

    Function GetTypeList(aList: TStrings):Boolean; This function will load a TStrings/TStringList with the available UnitKinds from the ConFactors file. (See example program)

4 - License information
===================
TConvEdit, TAlignEdit, TNumEdit, TDBMoreEdit, TConvFloatField, TConversion and TCustomalignEdit hereafter collectively called Controls are the exclusive property of P.A.S.S and Ron van Petegem.  The Controls are Shareware. If you distribute any software that contains any of the controls or parts thereof, you are required to obtain a registered version of controls BEFORE distributing.

Cost for the controls is $ 35.00 US dollar (55.- $ with source).  For a site license, please contact us as ronvanpetegem@compuserve.com.

Violation of this license may result in criminal prosecution and/or financial law suits.

How to Order: 

Send a E-mail to ronvanpetegem@compuserve.com and we will contact you with order information.

5 - DISCLAIMER
==============
P.A.S.S or Ron van Petegem will not be hold liable by any programmers, users, companies or any other person or persons or institution for any and/or all damages or any and/or all consequences that may arise from the use of this software. Through the use of this software you agree with this disclaimer.
